Dialogs and Alerts 

__________________________________________
GetNewDialog  *414*

Input names:   dialogID, dStorage, behind

Input types:   integer, Ptr, WindowPtr 

Output names:   DialogPtr

Output types:   DialogPtr

Description:   Creates a dialog as specified by its parameters and returns a pointer to the new dialog.  DialogID is the resource ID of a dialog template. DStorage is a pointer to the storage to use for the dialog record.  The behind parameter specifies the window behind which the dialog window is to be placed on the desktop.

__________________________________________
CloseDialog  *414*

Input names:   theDialog

Input types:   DialogPtr

Description:   Removes the dialog from the screen and deletes it from the window list.  Memory associated with the dialog window data structures and with dialog items is released, but the dialog record and item list are not disposed of.

__________________________________________
DisposDialog  *414*

Input names:   theDialog

Input types:   DialogPtr

Description:   Calls CloseDialog and then releases the memory occupied by the dialog’s item list and dialog record. 

__________________________________________
ModalDialog  *415*

Input names:   filterProc, itemHit

Input types:   ProcPtr, integer

Output names:   itemHit

Output types:   integer

Description:   Repeatedly gets and handles events in the dialog’s window; after handling an event involving an enabled dialog item, it returns with the item number in itemHit.  The filterProc parameter determines how events are filtered.  

__________________________________________
Invoking Alerts  *415*

In the following routines, the filterProc parameter determines how events are filtered. A filterProc of 0 leaves event processing up to the system.  The template for the alert, along with its buttons, static text items, and icons, is normally created using ResEdit.

__________________________________________
Alert  *415*

Input names:   alertID, filterProc

Input types:   integer, ProcPtr

Output names:   Integer

Output types:   integer

Description:   Invokes the alert defined by the alert template that has the given resource ID.  If no alert box is drawn at this stage, Alert returns a function result of -1; otherwise, it creates and displays the alert window for this alert and draws the alert box.

__________________________________________
StopAlert  *415*

Input names:   alertID, filterProc

Input types:   integer, ProcPtr

Output names:   Integer

Output types:   integer

Description:   Same as Alert (see above) except that before drawing the items of the alert in the alert box, it draws the Stop icon in the top left corner of the box.

__________________________________________
NoteAlert  *416*

Input names:   alertID, filterProc

Input types:   integer, ProcPtr

Output names:   Integer

Output types:   integer

Description:   Same as StopAlert (see above) except that it draws the Note icon.

__________________________________________
CautionAlert  *416*

Input names:   alertID, filterProc

Input types:   integer, ProcPtr

Output names:   Integer

Output types:   integer

Description:   Same as StopAlert (see above) except that it draws the Caution icon.

 

__________________________________________
Manipulating Items in Dialogs and Alerts

__________________________________________
ParamText  *416*

Input names:   param0, param1, param2, param3

Input types:   string, string, string, string

Description:   Provides a means of substituting text:   param0 through param3 will replace the special strings '^0' through '^3' in all statText items in all subsequent dialog or alert boxes.

__________________________________________
GetDItem  *417*

Input names:   theDialog, itemNo, itemType, item, box

Input types:   DialogPtr, integer, integer, Handle, Rect

Output names:   itemType, item, box

Output types:   integer, Handle, Rect

Description:   Returns in its var parameters the following information about the item numbered itemNo in the given dialog’s item list:   in the itemType parameter, the item type; in the item parameter, a handle to the item (or, for item type userItem, the procedure pointer); and in the box parameter, the display rectangle for the item.

__________________________________________
SetDItem  *417*

Input names:   theDialog, itemNo, itemType, item, box

Input types:   DialogPtr, integer, integer, Handle, Rect

Description:   Sets the item numbered itemNo in the given dialog’s item list, as specified by the parameters.  The parameters have the same meaning as in GetDItem (see above).

__________________________________________
GetIText  *417*

Input names:   item, text

Input types:   Handle, string

Output names:   text

Output types:   string

Description:   Given a handle in a dialog box, as returned by GetDItem (see above), GetIText returns the text of the item in the text parameter. 

__________________________________________
SetIText  *417*

Input names:   item, text

Input types:   Handle, string

Description:   Given a handle in a dialog box, as returned by GetDItem (see above), SetIText sets the text of the item to the specified text and draws the item.

__________________________________________
SelIText  *418*

Input names:   theDialog, itemNo, startSel, endSel

Input types:   DialogPtr, integer, integer, integer

Description:   Given a pointer to a dialog and the item number of an editText item in the dialog box, SelIText does the following:  

o
If the item contains text, SelIText sets the selection range to extend from character position startSel up to but not including character position endSel.  The selection range is inverted unless startSel equals endSel, in which case a blinking vertical bar is displayed to indicate an insertion point at that position.

o
If the item doesn’t contain text, SelIText simply displays the insertion point.

__________________________________________
Graphic Utilities 

__________________________________________
ScreenRes  *418*

Input names:   screenHRes, screenVRes

Input types:   integer, integer 

Output names:   screenHRes, screenVRes

Output types:   integer, integer 

Description:   Returns the resolution of the screen of the Macintosh being used.  ScreenHRes and screenVRes are the number of pixels per inch horizontally and vertically, respectively.

__________________________________________
GetIcon  *418*

Input names:   iconID 

Input types:   integer 

Output names:   Handle

Output types:   Handle 

Description:   Returns a handle to the icon having the given resource ID, reading it from the resource file, if necessary.  If the resource can’t be read, GetIcon returns NULL.

__________________________________________
PlotIcon  *419*

Input names:   theRect, theIcon

Input types:   Rect, Handle 

Description:   Draws the icon, whose handle is theIcon, in the rectangle theRect, which is the local coordinates of the current grafPort.

__________________________________________
GetPattern  *419*

Input names:   patID 

Input types:   integer 

Output names:   PatHandle

Output types:   PatHandle 

Description:   Returns a handle to the pattern having the given resource ID, reading it from the resource file, if necessary.  If the resource can’t be read, GetPattern returns NIL.

__________________________________________
GetIndPattern  *419*

Input names:   thePattern, patListID, index 

Input types:   Pattern, integer, integer 

Output names:   thePattern

Output types:   Pattern 

Description:   Returns in Integer a pattern in the pattern list that has the resource ID patListID, reading it from the resource file, if necessary.  The pattern is specified by the index parameter, which can range from 1 to the number of patterns in the pattern list.

__________________________________________
Miscellaneous Utilities 

__________________________________________
InvalRect  *419*

Input name:  
theRect

Input type:  
Rect

Description:   Adds the given rectangle into the update region of the current grafPort’s window.

__________________________________________
InvalRgn  *420*

Input name:  
theRgn

Input type:  
Handle

Description:   Adds the given region into the update region of the current grafPort’s window.

__________________________________________
SlopeFromAngle  *420*

Input names:   angle 

Input types:   integer 

Output names:   Fixed

Output types:   LongInt

Description:   Given an angle, SlopeFromAngle returns the slope dh/dv of the line forming that angle with the y-axis (dh/dv is the horizontal change divided by the vertical change between any two points on the line).

__________________________________________
AngleFromSlope  *420*

Input names:   slope 

Input types:   LongInt 

Output names:   angle

Output types:   integer

Description:   Given the slope dh/dv of a line (see SlopeFromAngle above), AngleFromSlope returns the angle formed by that line and the y-axis.  The angle returned is between 1 and 180 (inclusive), in degrees measured clockwise from 12 o’clock.

__________________________________________
GetMouse  *420*

Input names:   mouseLoc

Input types:   Point 

Output names:   mouseLoc

Output types:   Point

Description:   Returns the current mouse location in the mouseLoc parameter.  The location is given in the local coordinate system of the current grafPort (which might be, for example, the currently front window).

__________________________________________
Button  *421*

Output names:   Boolean

Output types:   boolean

Description:   Returns TRUE if the mouse button is currently down, and FALSE if it isn’t. 

__________________________________________
TickCount  *421*

Output names:   LongInt

Output types:   LongInt

Description:   Returns the current number of ticks (sixtieths of a second) since the system last started up.

__________________________________________
SysBeep  *421*

Input names:   duration

Input types:   integer

Description:   Causes the system to beep. If the speaker volume has been set to 0 (silent), SysBeep instead causes the menu bar to blink once. 

__________________________________________
SysEnvirons  *421*

Input names:   versRequested, theWorld

Input types:   integer, SysEnvRec

Output names:   error, theWorld

Output types:   integer, SysEnvRec

Description:   SysEnvirons is the standard way to determine the features on a given machine. It requires a version number for the type of SysEnvRec requested:    use a value of 1 for versRequested for all Systems before 6.0.1 and a value of 2 thereafter. The data structure theWorld is returned. Various fields of theWorld can be examined to discover the type of machine that the program is running on, if that machine has a floating point co-processor, color QuickDraw, what type of keyboard it has and so on.

NOTE:    Starting with later versions of System 6, using the Gestalt Manager is the recommended way of obtaining information about a system configuration.

__________________________________________
Field Constant Value   *422*

machineType   

 envMac
-1

 envXL
-2

 envMachUnknown
0

 env512KE
1

 envMacPlus
2

 envSE
3

 envMacII
4

 envMacIIx
5

 envMacIIcx
6

 envSE30
7

 envPortable
8

 envIIci
9

processor   

 envCPUUnknown
0

 env68000
1

 env68010
2

 env68020
3

 env68030
4

keyboardType   

 envUnknownKbd
0

 envMacKbd
1

 envMacAndPad
2

 envMacPlusKbd
3

 envAExtendKbd
4

 envStandADBKbd
5

 envPortADBKbd
6

 envPortISOADBKbd
7

 envStdISOADBKbd
8

 envExtISOADBKbd
9